{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using `scipy.integrate`\n",
    "\n",
    "## Authors\n",
    "Zach Pace, Lia Corrales, Stephanie T. Douglas\n",
    "\n",
    "## Learning Goals\n",
    "* perform numerical integration in the `astropy` and scientific python context\n",
    " * trapezoidal approximation\n",
    " * gaussian quadrature\n",
    "* use `astropy`'s built-in black-body curves\n",
    "* understand how `astropy`'s units interact with one another\n",
    "* define a Python class\n",
    " * how the `__call__` method works\n",
    "* add $\\LaTeX$ labels to `matplotlib` figures using the `latex_inline` formatter\n",
    "\n",
    "## Keywords\n",
    "modeling, units, synphot, OOP, LaTeX, astrostatistics, matplotlib, units, physics\n",
    "\n",
    "## Companion Content\n",
    "* http://synphot.readthedocs.io/en/latest/\n",
    "* [Using Astropy Quantities for astrophysical calculations](http://www.astropy.org/astropy-tutorials/rst-tutorials/quantities.html)\n",
    "\n",
    "## Summary\n",
    "In this tutorial, we will use the examples of the Planck function and the stellar initial mass function (IMF) to illustrate how to integrate numerically, using the trapezoidal approximation and Gaussian quadrature. We will also explore making a custom class, an instance of which is callable in the same way as a function. In addition, we will encounter `astropy`'s built-in units, and get a first taste of how to convert between them. Finally, we will use $\\LaTeX$ to make our figure axis labels easy to read."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from scipy import integrate\n",
    "from astropy.modeling.blackbody import blackbody_lambda, blackbody_nu, BlackBody1D\n",
    "from astropy import units as u, constants as c\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Planck function\n",
    "\n",
    "The Planck function describes how a black-body radiates energy. We will explore how to find bolometric luminosity using the Planck function in both frequency and wavelength space."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's say we have a black-body at 5000 Kelvin. We can find out the total intensity (bolometric) from this object, by integrating the Planck function. The simplest way to do this is by approximating the integral using the trapezoid rule. Let's do this first using the frequency definition of the Planck function.\n",
    "\n",
    "We'll define a photon frequency grid, and evaluate the Planck function at those frequencies. Those will be used to numerically integrate using the trapezoidal rule. By multiplying a `numpy` array by an `astropy` unit, we get a `Quantity`, which is effectively a combination of one or more numbers and a unit."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "**Note on printing units**: \n",
    "\n",
    "Quantities and units can be printed to strings using the [Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax). This demonstration uses the `latex_inline` format that is built in to the `astropy.units` package. To see additional ways to format quantities, see the [Getting Started](http://docs.astropy.org/en/stable/units/#getting-started) section of the astropy.units documentation pages.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nu = np.linspace(1., 3000., 1000) * u.THz\n",
    "bb5000K_nu = blackbody_nu(in_x=nu, temperature=5000. * u.Kelvin)\n",
    "plt.plot(nu, bb5000K_nu)\n",
    "plt.xlabel(r'$\\nu$, [{0:latex_inline}]'.format(nu.unit))\n",
    "plt.ylabel(r'$I_{\\nu}$, ' + '[{0:latex_inline}]'.format(bb5000K_nu.unit))\n",
    "plt.title('Planck function in frequency')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using $LaTeX$ for axis labels\n",
    "\n",
    "Here, we've used $LaTeX$ markup to add nice-looking axis labels. To do that, we enclose $LaTeX$ markup text in dollar signs, within a string `r'\\$ ... \\$'`. The `r` before the open-quote denotes that the string is \"raw,\" and backslashes are treated literally. This is the suggested format for axis label text that includes markup.\n",
    "\n",
    "Now we numerically integrate using the trapezoid rule."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.trapz(x=nu, y=bb5000K_nu).to('erg s-1 cm-2 sr-1')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can do something similar, but for a wavelength grid. We want to integrate over an equivalent wavelength range to the frequency range we did earlier. We can transform the maximum frequency into the corresponding (minimum) wavelength by using the `.to()` method, with the addition of an *equivalency*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "lam = np.linspace(nu.max().to(u.AA, equivalencies=u.spectral()),\n",
    "                  nu.min().to(u.AA, equivalencies=u.spectral()), 1000)\n",
    "bb5000K_lam = blackbody_lambda(in_x=lam, temperature=5000. * u.Kelvin)\n",
    "plt.plot(lam, bb5000K_lam)\n",
    "plt.xlim([1.0e3, 5.0e4])\n",
    "plt.xlabel(r'$\\lambda$, [{0:latex_inline}]'.format(lam.unit))\n",
    "plt.ylabel(r'$I_{\\lambda}$, ' + '[{0:latex_inline}]'.format(bb5000K_lam.unit))\n",
    "plt.title('Planck function in wavelength')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.trapz(x=lam, y=bb5000K_lam).to('erg s-1 cm-2 sr-1')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice this is within a couple percent of the answer we got in frequency space, despite our bad sampling at small wavelengths!\n",
    "\n",
    "Many `astropy` functions use units and quantities directly. As you gain confidence working with them, consider incorporating them into your regular workflow. Read more [here](http://docs.astropy.org/en/stable/units/) about how to use units."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### How to simulate actual observations\n",
    "\n",
    "As of Fall 2017, `astropy` does not explicitly support constructing synthetic observations of models like black-body curves. The [synphot library](https://synphot.readthedocs.io/en/latest/) does allow this. You can use `synphot` to perform tasks like turning spectra into visual magnitudes by convolving with a filter curve."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The stellar initial mass function (IMF)\n",
    "\n",
    "The stellar initial mass function tells us how many of each mass of stars are formed. In particular, low-mass stars are much more abundant than high-mass stars are. Let's explore more of the functionality of `astropy` using this concept.\n",
    "\n",
    "People generally think of the IMF as a power-law probability density function. In other words, if you count the stars that have been born recently from a cloud of gas, their distribution of masses will follow the IMF. Let's write a little class to help us keep track of that:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class PowerLawPDF(object):\n",
    "    def __init__(self, gamma, B=1.):\n",
    "        self.gamma = gamma\n",
    "        self.B = B\n",
    "    def __call__(self, x):\n",
    "        return x**self.gamma / self.B"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The `__call__` method\n",
    "\n",
    "By defining the method `__call__`, we are telling the Python interpreter that an instance of the class can be called like a function. When called, an instance of this class, takes a single argument, `x`, but it uses other attributes of the instance, like `gamma` and `B`.\n",
    "\n",
    "### More about classes\n",
    "\n",
    "Classes are more advanced data structures, which can help you keep track of functionality within your code that all works together. You can learn more about classes in [this tutorial](https://www.codecademy.com/ja/courses/learn-python/lessons/introduction-to-classes/exercises/why-use-classes)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Integrating using Gaussian quadrature\n",
    "\n",
    "In this section, we'll explore a method of numerical integration that does not require having your sampling grid set-up already. `scipy.integrate.quad` with reference [here](https://docs.scipy.org/doc/scipy-0.19.1/reference/generated/scipy.integrate.quad.html) takes a function and both a lower and upper bound, and our `PowerLawPDF` class takes care of this just fine.\n",
    "\n",
    "Now we can use our new class to normalize our IMF given the mass bounds. This amounts to normalizing a probability density function. We'll use Gaussian quadrature (`quad`) to find the integral. `quad` returns the numerical value of the integral and its uncertainty. We only care about the numerical value, so we'll pack the uncertainty into `_` (a placeholder variable). We immediately throw the integral into our IMF object and use it for normalizing!\n",
    "\n",
    "To read more about *generalized packing and unpacking* in Python, look at the original proposal, [PEP 448](https://www.python.org/dev/peps/pep-0448/), which was accepted in 2015."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "salpeter = PowerLawPDF(gamma=-2.35)\n",
    "salpeter.B, _ = integrate.quad(salpeter, a=0.01, b=100.)\n",
    "\n",
    "m_grid = np.logspace(-2., 2., 100)\n",
    "plt.loglog(m_grid, salpeter(m_grid))\n",
    "plt.xlabel(r'Stellar mass [$M_{\\odot}$]')\n",
    "plt.ylabel('Probability density')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### How many more M stars are there than O stars?\n",
    "\n",
    "Let's compare the number of M dwarf stars (mass less than 60% solar) created by the IMF, to the number of O stars (mass more than 15 times solar)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "n_m, _ = integrate.quad(salpeter, a=.01, b=.6)\n",
    "n_o, _ = integrate.quad(salpeter, a=15., b=100.)\n",
    "print(n_m / n_o)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are almost 21000 as many low-mass stars born as there are high-mass stars!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Where is all the mass?\n",
    "\n",
    "Now let's compute the relative total masses for all O stars and all M stars born. To do this, weight the Salpeter IMF by mass (i.e., add an extra factor of mass to the integral). To do this, we define a new function that takes the old power-law IMF as one of its arguments. Since this argument is unchanged throughout the integral, it is passed into the tuple `args` within `quad`. It's important that there is only *one* argument that changes over the integral, and that it is the *first* argument that the function being integrated accepts.\n",
    "\n",
    "Mathematically, the integral for the M stars is\n",
    "\n",
    "$$ m^M = \\int_{.01 \\, M_{\\odot}}^{.6 \\, M_{\\odot}} m \\, {\\rm IMF}(m) \\, dm $$\n",
    "\n",
    "and it amounts to weighting the probability density function (the IMF) by mass. More generally, you find the value of some property $\\rho$ that depends on $m$ by calculating\n",
    "\n",
    "$$ \\rho(m)^M = \\int_{.01 \\, M_{\\odot}}^{.6 \\, M_{\\odot}} \\rho(m) \\, {\\rm IMF}(m) \\, dm $$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def IMF_m(m, imf):\n",
    "    return imf(m) * m\n",
    "\n",
    "m_m, _ = integrate.quad(IMF_m, a=.01, b=.6, args=(salpeter, ))\n",
    "m_o, _ = integrate.quad(IMF_m, a=15., b=100., args=(salpeter, ))\n",
    "\n",
    "m_m / m_o"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So about 20 times as much mass is tied up in M stars as in O stars."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Extras\n",
    "\n",
    "* Now compare the total luminosity from all O stars to total luminosity from all M stars. This requires a mass-luminosity relation, like this one which you will use as $\\rho(m)$:\n",
    "\n",
    "$$\n",
    " \\frac{L}{L_{\\odot}} (M) =\n",
    "  \\begin{cases} \n",
    "      \\hfill .23 \\left( \\frac{M}{M_{\\odot}} \\right)^{2.3} \\hfill , \\hfill & .1 < \\frac{M}{M_{\\odot}} < .43 \\\\\n",
    "      \\hfill \\left( \\frac{M}{M_{\\odot}} \\right)^{4} \\hfill , \\hfill & .43 < \\frac{M}{M_{\\odot}} < 2 \\\\\n",
    "      \\hfill 1.5 \\left( \\frac{M}{M_{\\odot}} \\right)^{3.5} \\hfill , \\hfill & 2 < \\frac{M}{M_{\\odot}} < 20 \\\\\n",
    "      \\hfill 3200 \\left( \\frac{M}{M_{\\odot}} \\right) \\hfill , \\hfill & 20 < \\frac{M}{M_{\\odot}} < 100 \\\\\n",
    "  \\end{cases},\n",
    "$$\n",
    "\n",
    "* Think about which stars are producing most of the light, and which stars have most of the mass. How might this result in difficulty inferring stellar masses from the light they produce? If you're interested in learning more, see [this review article](https://ned.ipac.caltech.edu/level5/Sept14/Courteau/Courteau_contents.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Challenge problems\n",
    "\n",
    "* Right now, we aren't worried about the bounds of the power law, but the IMF should drop off to zero probability at masses below .01 solar masses and above 100 solar masses. Modify `PowerLawPDF` in a way that allows both `float` and `numpy.ndarray` inputs.\n",
    "* Modify the `PowerLawPDF` class to explicitly use `astropy`'s `units` constructs.\n",
    "* Derive a relationship between recent star-formation rate and $H\\alpha$ luminosity. In other words, find a value of $C$ for the function\n",
    "\n",
    "$${\\rm SFR \\, [\\frac{M_{\\odot}}{yr}]} = {\\rm C \\, L_{H\\alpha} \\, [\\frac{erg}{s}]} \\, .$$\n",
    "\n",
    "* How does this depend on the slope and endpoints of the IMF?\n",
    "* Take a look at Appendix B of [Hunter & Elmegreen 2004, AJ, 128, 2170](http://adsabs.harvard.edu/cgi-bin/bib_query?arXiv:astro-ph/0408229)\n",
    "* What effect does changing the power-law index or upper mass limit of the IMF have on the value of $C$?\n",
    "* Predict the effect on the value of $C$ of using a different form of the IMF, like Kroupa or Chabrier (both are lighter on the low-mass end).\n",
    "* If you're not tired of IMFs yet, try defining a new class that implements a broken-power-law (Kroupa) or log-parabola (Chabrier) IMF. Perform the same calculations as above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
